fix(extractor): compile StyleX position and view-transition contracts - #762

Refs #690 (W37: StyleX position/view-transition identity, API 및 entrypoint). #758 위에 쌓은 브랜치이며 #758이 먼저 병합되어야 합니다. PR base는 main입니다.

요약

• 같은 파일의 positionTry()/viewTransitionClass() 호출이 파일명과 API명만으로 같은 이름을 받던 충돌을 수정합니다.
• viewTransitionClass()의 group, imagePair, old, new를 실제 view-transition pseudo-element 규칙으로 컴파일합니다. 일반 DOM 클래스 규칙을 출력하지 않습니다.
• 문서·타입·package exports에 있는 StyleX entrypoint를 빌드의 import 인식, 정적 평가, 모듈 해석 및 hasDevupUI gate와 맞춥니다. 알려진 StyleX API 호출은 컴파일되거나 원본 위치의 빌드 오류가 되며 JS에 남지 않습니다.
• public transition 타입과 억제 주석 없는 양성·음성 타입 소비자 테스트를 추가합니다. 변경 패키지는 모두 Patch입니다.
• W37b 후속 커밋에서 알려진 API의 .call/.apply/.bind 및 함수값 escape, 모든 표현식 위치의 types-only loader를 차단하고 Linux CI의 48개 uncovered line을 의미 있는 회귀 테스트로 보완합니다.

동작

이름과 선언

하나의 injective 이름 함수가 파일 식별자·API 구분·canonical 내용을 구분자가 포함된 UTF-8 hex로 lossless encoding합니다. 방문 순서, 다른 파일, 클래스 번호 counter, 유한 hash를 사용하지 않아 서로 다른 입력 identity의 충돌 가능성이 남지 않습니다. 같은 파일의 같은 canonical 내용은 이름을 공유합니다. positionTry 선언은 정렬하고, view-transition 슬롯과 선언은 upstream과 같이 enumeration 순서를 보존합니다. 빈 객체와 명시적인 빈 슬롯은 다릅니다. keyframes/변수 참조를 통해 counter가 다시 유입되지 않도록 필요한 StyleX dependency 이름도 같은 함수를 사용합니다.

숫자 길이는 px, duration은 ms, fontWeight/opacity 등은 올바른 unitless 값입니다. Devup spacing 배율을 적용하지 않습니다. 선언의 정적으로 알려진 null/undefined/false는 생략하며, 마지막 중복 선언이 생략 값이면 앞선 값도 남지 않습니다. 슬롯 자체는 flat 선언 객체여야 합니다.

외부 모듈에서 평가한 view-transition 상수도 같은 계약을 사용합니다. 상수를 JS literal로 재구성할 때 생기는 중첩 record의 괄호를 adapter에서 제거해, 유효한 슬롯 객체가 읽히지 않던 문제를 회귀 테스트로 수정했습니다.

Upstream 계약과 의도적 차이

대상은 설치된 @stylexjs/babel-plugin@0.19.1 및 immutable commit 1fcb9a51cbecad2c82255e0f4b45cc072fa1a95a입니다. 실제 Babel probe도 수행하여 아래 upstream 출력과 omission을 확인했습니다.

• 슬롯/선택자: visitor 151–168, shared compiler 48–67, 100–107.
• Position whitelist와 정렬/내용 identity: visitor 119–175, shared compiler 30–60, 90–104.
• Upstream tuple 버그는 재현하지 않습니다. positionTry({top:0,width:100})의 upstream LTR 출력은 top:top;top:0;width:width;width:100px;이지만 Devup은 유효한 top:0;width:100px;만 출력합니다. tuple 변환 41–58, serializer 94–101.
• Upstream 숫자 단위 버그도 재현하지 않습니다. animationDuration:500,fontWeight:700의 실제 upstream 출력은 animation-duration:500px;font-weight:700px;입니다. Devup은 500ms와 unitless 700을 사용합니다. dashify 후 lookup 38–44, suffix 표 109–182.
• Upstream은 정적 true/배열/객체 선언까지 조용히 버립니다. Devup은 null/undefined/false만 생략하고, 작성한 값을 조용히 잃지 않도록 다른 unsupported 값은 위치·API·슬롯·키·값 종류를 포함한 오류로 보고합니다. position filter 63–83, view filter 70–90.

Entry Sources

실제 entrypoint가 존재하므로 package exports를 만들거나 제거하지 않고 빌드 인식을 수정했습니다. stylex라는 unscoped source, 임의 prefix/subpath, root의 개별 positionTry export를 새로 인정하지 않습니다. 기존 generic root default namespace는 StyleX default entrypoint와 구분하여 다른 Devup 동작을 보존합니다.

최종 public surface는 PositionTryStyles(40개의 optional position key), ViewTransitionStyles(optional 네 슬롯), StylexDeclarations(flat string | number | null | undefined | false leaf)입니다. 기존 root namespace와 실제 /stylex export 및 upstream ambient 타입에 반영합니다. W24의 타입 PR은 이전 베이스가 컴파일하던 flat transition surface를 기준으로 하므로, 두 PR 중 나중에 병합하는 쪽이 이 최종 네 슬롯 계약으로 타입을 reconcile해야 합니다.

PositionTryStyles의 최종 허용 key는 다음 40개입니다(모두 optional, readonly):

anchorName, positionAnchor, positionArea,
top, right, bottom, left, inset, insetBlock, insetBlockEnd, insetBlockStart,
insetInline, insetInlineEnd, insetInlineStart,
margin, marginBlock, marginBlockEnd, marginBlockStart, marginInline,
marginInlineEnd, marginInlineStart, marginTop, marginBottom, marginLeft, marginRight,
width, height, minWidth, minHeight, maxWidth, maxHeight,
blockSize, inlineSize, minBlockSize, minInlineSize, maxBlockSize, maxInlineSize,
alignSelf, justifySelf, placeSelf

ESLint의 css-utils-literal-only도 같은 source와 lexical binding을 인식합니다. 변경한 rule 경로는 index.ts, 신규 stylex-bindings.ts, 신규 __tests__/stylex-bindings.test.ts이며 모두 packages/eslint-plugin/src/rules/css-utils-literal-only/ 아래입니다. W24 lint 스택과 병합할 때 이 세 경로를 reconcile해야 합니다. 다른 ESLint rule은 수정하지 않았습니다.

새로 생기는 오류

모두 파일:줄:열: <API> cannot use <코드> at build time: <필요한 입력> 형식의 위치와 원인을 포함합니다.

• positionTry()의 whitelist 밖 key, CSS kebab-case alias/custom-property key, 또는 viewTransitionClass()의 네 슬롯 밖 key/기존 flat 선언 입력.
• view 슬롯에 flat 선언 객체 대신 scalar/null/undefined/false/배열/함수를 전달한 경우.
• 선언에 정적인 true/배열/객체/함수, 중첩 default/pseudo/media 조건, unsupported shorthand fallback 배열을 전달한 경우. API·슬롯·선언 key·값 종류·허용 모양을 명시합니다.
• 값/인자/spread/computed key를 정확히 해석할 수 없는 경우, getter/setter/메서드, 잘못된 인자 개수/모양. 새로 인식하는 source에도 같은 정적 계약을 적용합니다.
• 존재하지 않는 StyleX value export/default, types-only compat의 value import/require, 남은 실제 API 호출/함수·namespace escape, 해석할 수 없는 API 선택/optional/computed 접근 또는 API 재수출.
• 알려진 API 함수의 .call/.apply/.bind(literal computed 및 분리한 member 포함), 다른 호출의 인자 전달, 객체·배열 저장은 API명·사용 형태·원본 위치와 call the API directly 해결 방법을 포함한 오류입니다. 기존 named import, alias, namespace member의 직접 호출은 계속 컴파일하며 관련 없는 member 및 shadowed 사용자 함수는 보존합니다.
• types-only @devup-ui/react/compat/stylex를 member call의 loader, 단독 require, 대입, 인자·객체·배열, 허용된 root loader의 중첩 인자 또는 dynamic import로 실행해도 loader 위치에서 오류입니다. type-only import와 import-type 참조, shadowed require는 보존합니다.
• 허용된 root require 선언의 destructuring computed key/default/nested/array/rest pattern에서도 실행 가능한 loader/API 표현식을 검사합니다. 바깥쪽의 지원된 loader 자체와 선언용 binding identifier, 일반 runtime default와 erased type은 그대로 보존합니다.
• 실제 API loader의 잘못된 arity/unsupported destructuring, 직접 root loader의 StyleX projection, whole-loader assignment 등 지원되지 않는 loader 형태. source가 비슷하거나 require가 shadowed인 일반 코드를 StyleX로 처리하지 않으며, runtime-only root 사용은 보존합니다.
• 새로 인식하는 root/subpath/alias API의 runtime parameter·let 등 값에 기존 ESLint cssUtilsLiteralOnly 진단이 발생합니다. 새 messageId나 억제 주석은 추가하지 않았습니다.

남는 한계

• 이름은 opaque하며 파일 식별자와 내용 길이에 비례하여 기존 counter 이름보다 깁니다. 현재 베이스의 파일 식별자를 사용하므로 W31 environment-stable naming 스택 병합 때 이 단일 derivation을 함께 조정해야 합니다.
• view-transition 선언은 flat 정적 값만 지원합니다. JS runtime 값, 중첩 조건/스타일링 함수, 외부 모듈 코드 실행을 styling runtime으로 우회하지 않습니다. 정적 var(...) 문자열은 사용할 수 있습니다.
• 공식 entrypoint의 지원된 literal-source loader 형태를 사용해야 합니다. 임의 loader나 정적으로 증명되지 않은 source를 이름만으로 StyleX라고 추측하지 않습니다.

검증

수정 전 real-WASM probe: 서로 다른 position 호출이 모두 --a, 서로 다른 flat view 호출이 모두 a; 네 슬롯 객체는 오류; 실제 root/subpath import의 API 호출은 JS에 남았습니다.

// before: w37-identities.tsx
export const a = "--a";
export const b = "--a";
// @position-try --a{top:1px;}@position-try --a{top:2px;}

변경 후 real-WASM 출력 (/src/qa.tsx; styling runtime import 없이 실제 실행):

export const a = "--sxp-2f7372632f71612e747378-746f703a3170783b-";
export const b = "--sxp-2f7372632f71612e747378-746f703a3270783b-";
export const c = "--sxp-2f7372632f71612e747378-746f703a3170783b-";

@position-try --sxp-2f7372632f71612e747378-746f703a3170783b-{top:1px;}
@position-try --sxp-2f7372632f71612e747378-746f703a3270783b-{top:2px;}
::view-transition-old(*.sxv-2f7372632f71612e747378-3a3a766965772d7472616e736974696f6e2d6f6c643a6f7061636974793a303b3b-){opacity:0;}
::view-transition-old(*.sxv-2f7372632f71612e747378-3a3a766965772d7472616e736974696f6e2d6f6c643a6f7061636974793a313b3b-){opacity:1;}

W24의 root 및 subpath create/props JSX fixture는 모두 아래 실제 출력으로 바뀝니다:

import "@devup-ui/react/devup-ui.css";
const styles = { "root": "a" };
export const App = <div {...{ className: "a" }} />;
// CSS: .a{color:red}

기존 flat viewTransitionClass({animationDuration:'1s'})는 이제 위치가 포함된 오류입니다. 예: w37-flat.tsx:2:56: stylex.viewTransitionClass() cannot use animationDuration ... its slots are group, imagePair, old and new. Runtime duration은 w37-runtime.tsx:3:67의 실제 leaf duration, 슬롯 group, 선언 animationDuration을 명시합니다.

• 139개 real-WASM QA 행 통과: 기존 identity/슬롯/omission/순서/entrypoint와 B1/B2 matrix, named/alias/namespace/root/CJS 직접 호출, 관련 없는 member와 shadowed control, API member 변경·namespace export의 실제 source별 오류 경로, R1 binding-pattern 오류·shadowed loader·실제 mixed root 실행, Vite의 JS main-CSS import 및 Webpack의 file-CSS → main-CSS import 전달까지 실제 출력을 확인했습니다. CSS import만 실행 adapter에서 처리하며 StyleX import/call을 제거하지 않았습니다.
• 최종 cargo test --workspace: 총 3,241 통과/0 실패, extractor 2,524 unit + 3 integration 포함. 기존 focused StyleX 635, residual suite 38에 더해 R1 전용 28 cases 통과; Rust 1.99 strict workspace/all-target clippy 및 fmt 통과.
• WASM 및 루트 bun run build, declared dist entrypoint 검증 통과. Source 타입 harness와 실제 dist/package exports를 복사한 consumer에서 각각 1 positive + 19 negative 통과.
• 네 후속 exact-tree 커밋의 unskipped hook 통과: lint, 정상 local tarpaulin, Bun 6,326 통과/0 실패/89 snapshots. Targeted ESLint rule/helper functions+lines 100%, 1,004 tests 통과. 전체 Bun 표는 aggregate 100%로 반올림되지만 변경하지 않은 Vite plugin의 Windows line 303은 99.63%이므로 이를 exact whole-suite 100%라고 주장하지 않습니다. Lint의 기존 경고 2개 외 새 경고는 없습니다.
• 최종 Windows narrow-format hook tarpaulin은 **97.37% (20,014/20,555)**입니다. Linux가 authority이며 local wide-format lane, threshold 변경, coverage 제외, hook skip은 사용하지 않았습니다. 첫 커밋에서 다른 커밋의 세 파일만 approved exact-tree stash로 보관해 staged-only tree를 재빌드·검증한 후 commit했고, 기록한 고유 hash로 복원했습니다. 다른 worker의 stash는 건드리지 않았습니다.
• LSP daemon은 Rust 요청 timeout, TypeScript/Biome은 설치가 사전에 거절되어 unavailable입니다. clean LSP를 주장하지 않으며 실제 compiler/test/lint 결과를 기록합니다.
• 첫 Linux run 37335990069 (1ec8eff3)은 Rust tests가 모두 통과했으나 99.67% (14,347/14,395), 변경 코드 48 uncovered line 때문에 실패했습니다. Codecov outage가 아니며 뒤의 Bun CI는 실행되지 않았습니다. 그 48개 line은 unique 임시 HEAD tree의 CI-format mapping으로 추적했고 회귀 테스트와 불가능한 guard의 제거로 보완했습니다.
• 중간 head f99c5eb4adfad3d5bd054499b4e16f96ba12f942(커밋 09dd7d3d + f99c5eb4)의 Linux run 37359456436은 **99.97% (14,443/14,448)**였습니다. 원래 48개 miss는 모두 닫혔고 새 boundary 파일 두 개의 5개 line을 추가 보완했습니다. Build/entrypoint/tarball/lint 및 다른 세 job은 통과했으나 당시 publish의 coverage threshold에서 멈췄으므로 Codecov outage가 아니었습니다.
• 이후 head 667aa623025002322b2c3506bae60b6fadbbc928, Linux run 37366885193: publish job 전체 통과, Rust **100.00% (14,448/14,448)**였습니다. 마지막 5개 line도 실제 mutation/export 및 shadowed control 회귀 테스트로 닫혔습니다. publish의 build/entrypoint/tarball/lint/Rust+Bun/landing E2E 등 실행된 필수 검증은 모두 통과했습니다.
• 같은 최종 run의 benchmark, landing-next-e2e, vinext-rsc-css-e2e는 실행 step 없이 cancelled되었습니다. Coordinator가 확인한 GitHub-hosted runner 할당 장애(04:11 KST부터, The job was not acquired by Runner of type hosted even after multiple attempts)이며 코드 실패나 Codecov 장애가 아닙니다. 전체 run을 green이라고 주장하지 않습니다. Workflow를 변경하거나 반복 재실행하지 않았으며, GitHub 복구 후 coordinator가 취소된 job을 재실행합니다. 직전 f99c5eb4의 동일 production source에서는 이 세 job이 모두 통과했고, 마지막 커밋은 test-only입니다.
• 첫 delta-scoped semantic review는 R1(허용된 root require 선언의 computed key/default subtree 누락)을 지적했습니다. 실제 667aa623 WASM에서 여섯 JS 잔존을 재현한 뒤, 기존 Oxc visit_binding_pattern 호출 한 줄로 올바른 seam을 수정했습니다. 바깥 loader 예외·runtime pattern·shadowing·erased type을 보존하는 adjacent 28 cases와 rebuilt 139 QA로 확인했으며, 새 R1-only gate verdict는 APPROVE / HIGH, 남은 semantic blocker는 없습니다.
• 최종 head ca0d7168e7b07db93063b0c2701a432edb9d322e, 최종 Linux run **37374977910**는 전체 SUCCESS입니다. Rust 100.00% (14,449/14,449), publish, benchmark, landing-next-e2e, vinext-rsc-css-e2e 네 job 모두 통과했습니다. 최종 run에는 outage 예외를 적용할 필요가 없습니다. PR은 ready로 전환하며 병합·close·approve는 하지 않습니다.

B1/B2 실제 전후 출력

수정 전에는 아래 호출과 loader가 JS에 그대로 남았습니다 (w37b-before-boundary.json).

export const result = pt.call(null, { top: 1 });
export const result = require("@devup-ui/react/compat/stylex").positionTry({ top: 1 });
export const result = import("@devup-ui/react/compat/stylex");

동일 입력의 수정 후 real-WASM 결과 (w37b-after-boundary.json):

/src/B1-call.tsx:2:23: `stylex.positionTry()` cannot use `pt.call` at build time: unsupported invocation/binding member; call the API directly
/src/B1-pass-value.tsx:2:31: `stylex.positionTry()` cannot use `pt` at build time: unsupported argument passing; call the API directly
/src/B2-member.tsx:1:23: `StyleX API()` cannot use `require` at build time: compat/stylex has only type exports; use the real stylex entrypoint
/src/B2-dynamic-import.tsx:1:23: `StyleX API()` cannot use `import(...)` at build time: compat/stylex has only type exports; use the real stylex entrypoint

R1 binding pattern도 동일 입력의 before/after를 기록했습니다:

// before: computed key 안의 loader가 그대로 남음
const { [require("@devup-ui/react/compat/stylex")]: value } = require("@devup-ui/react");

// after: 바깥 supported loader가 아닌 실제 inner loader 위치
/src/R1-computed-require.tsx:1:10: `StyleX API()` cannot use `require` at build time: compat/stylex has only type exports; use the real stylex entrypoint
/src/R1-computed-call.tsx:2:10: `stylex.positionTry()` cannot use `pt.call` at build time: unsupported invocation/binding member; call the API directly

2026-10-08 main 11790bef를 병합하여 업데이트했습니다. 충돌 없이 갱신된 부모 PR의 변경과 main의 변경을 모두 보존했습니다.